Authentication Workflow
When someone claiming to be an end user
A person who is a customer, patient, constituent, or client of a Jumio customer, and who participates in the “customer journey” as part of their interaction with the Jumio customer. you have already onboarded returns to your platform, use Jumio Authentication to make sure they really are the same person. Jumio Authentication captures a fresh Selfie and Facemap and compares them to an existing Facemap that is already associated with the end-user account.
Typically the existing Facemap is the one that was acquired when the end user was first onboarded using the Identification Document and Identity Verification (IDIV) Workflow. Depending on your organization's Data Retention policy (See Data Settings) that Facemap is:
-
Stored on Jumio's servers, and associated with the account
A grouping of credentials and transactions associated with an end user. if it is within the configured Data retention period. -
Deleted from Jumio's servers if it is beyond the configured Data retention period. In that case if you want to use Authentication you must download the Facemap, store it on your own servers, and upload it prior to running Authentication with a new Facemap. See Authentication On-Premises for detailed instructions.
When you have an existing end user account with an existing Facemap, the process to authenticate the same user is as follows:
-
Update the Account to Initiate an Authentication Transaction
-
Complete the Customer Journey for the Authentication Transaction
Update the Account to Initiate an Authentication Transaction
Use the PUT request for the Accounts API to update the existing end user account. The account ID value saved from the on-boarding transaction is used as a path parameter in the request URL.
In the request body, specify workflow key 10014 to use the standard Authorization workflow.
Example Request Body
{
"customerInternalReference":"MyCompany", "workflowDefinition":{"key": 10014 }
}
Providing the End-User Consent
If your integration uses one of the Mobile SDKs with a custom user interface you can use the original consent obtained when the end user was onboarded instead of requiring the end user to provide an explicit consent for each authentication transaction. In this case you must have recorded the timestamp from the onboarding, and be able to use it to set the userConsent values, as shown in the example below. The original consent can be valid for a maximum of 3 years. Beyond that the end user must explicitly provide the consent, as described in End-User Consent to Collect Personal Data.
{
"customerInternalReference":"MyCompany", "workflowDefinition":{"key": 10014 },
"userConsent":
"consent": {
"obtained": "yes",
"obtainedAt": "2022-07-20T17:20:35.000Z"
}
}
}
Complete the Customer Journey for the Authentication Transaction
Authentication requires your integration to use either the Web Client or one of the Mobile SDKs. A new Facemap is required, which cannot be uploaded through the REST APIs. See Credential Acquisition for additional information.
The end user is guided to take the new Selfie and Facemap. When they have been successfully uploaded the workflow is finalized.
Retrieve the Decision
If your integration has integrated a Callback service it will be notified when the transaction is complete. Alternatively you can call the Transaction Status API to determine if the transaction has been PROCESSED.
Once the transaction has completed you can call the Workflow Details API to retrieve the decision and other workflow data.
Example Details Response
{
"workflow": {
"id": "a6692412-a1e1-4fbc-a3fa-79c210af25b6",
"status": "PROCESSED",
"definitionKey": "10014",
"customerInternalReference": "MyCompany"
},
"account": {
"id": "2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f"
},
"createdAt": "2023-04-19T17:54:28.218Z",
"startedAt": "2023-04-19T17:55:15.170Z",
"completedAt": "2023-04-19T17:55:16.126Z",
"credentials": [
{
"id": "c4daab5f-bbe7-4fea-8d0e-1e6a9fa0094a",
"category": "SELFIE",
"parts": [
{
"classifier": "FACE",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/c4daab5f-bbe7-4fea-8d0e-1e6a9fa0094a/parts/FACE"
}
]
},
{
"id": "4915434a-9b0f-4bbf-b088-dfea00b4b680",
"category": "FACEMAP",
"parts": [
{
"classifier": "FACEMAP"
},
{
"classifier": "LIVENESS_1",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_1"
},
{
"classifier": "LIVENESS_3",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_3"
},
{
"classifier": "LIVENESS_2",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_2"
},
{
"classifier": "LIVENESS_5",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_5"
},
{
"classifier": "LIVENESS_4",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_4"
},
{
"classifier": "LIVENESS_6",
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/LIVENESS_6"
}
]
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "PASSED"
},
"risk": {
"score": 0.0
}
},
"steps": {
"href": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/workflow-executions/a6692412-a1e1-4fbc-a3fa-79c210af25b6/steps"
},
"capabilities": {
"usability": [
{
"id": "7023c47c-6c61-4bba-acd7-b00d053318dc",
"credentials": [
{
"id": "c4daab5f-bbe7-4fea-8d0e-1e6a9fa0094a",
"category": "SELFIE"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
},
{
"id": "0bc1e60d-e33e-47aa-8f72-c3eb6348ea81",
"credentials": [
{
"id": "4915434a-9b0f-4bbf-b088-dfea00b4b680",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
}
}
],
"authentication": [
{
"id": "9f25965a-4073-4051-a02c-aa5a4d175a77",
"validFaceMapForAuthentication": "https://retrieval.amer-1.jumio.ai/api/v1/accounts/2568c760-0a5b-4a07-bbcf-d7a4e5cd5b2f/credentials/4915434a-9b0f-4bbf-b088-dfea00b4b680/parts/FACEMAP",
"credentials": [
{
"id": "4915434a-9b0f-4bbf-b088-dfea00b4b680",
"category": "FACEMAP"
}
],
"decision": {
"type": "PASSED",
"details": {
"label": "OK"
}
},
"data": {
"type": "IPROOV_STANDARD"
}
}
]
}
}